(SST) ShlWAPI.pas Version 1.08

Developer Reference
SST ShlWAPI StrFormatByteSize64A Function
Creates a string from a signed, 64-bit integer value, that is a user friendly representation of its size, expressed in either bytes, KBytes, MBytes, or GBytes.
Scope
Global (i.e. this function can be called/accessed from code in any unit that includes/uses (SST)ShlWAPI.pas).
Syntax
function StrFormatByteSize64A(qdw : LONGLONG; pszBuf : LPSTR; cchBuf : UINT) : LPSTR;
Parameters
qdw [in] The signed, 64-bit integer value for which a standardized size, string represntation is requested.
pszBuf [in] The pointer to the null terminated buffer into which the function should write the output string.
cchBuf [in] The size, in number of single byte (i.e. ANSI) characters of the buffer pointed to by pszBuf.
Return Values
Returns a pointer to the standardized size string, or NIL if the function failed.
Remarks
This function supports ANSI strings only.
Although the function, according to Microsoft, belying its name, also supports Unicode output buffers, the SST (ShlWAPI.pas) declaration/implementation is limited to the ANSI version.
The function (as implemented in ShlWAPi.dll version 6.0.6000.16386 (vista_rtm.061101-2205)) appears to merely perform a character conversion and then calls StrFormatByteSizeW. StrFormatByteSize64A can therefore be considered the true, ANSI equivalent to StrFormatByteSizeW, and not, as suggested by its name, StrFormatByteSizeA.
Example
PROCEDURE TForm4.TestShlWAPIStrFormatByteSize64A(Sender : TObject); VAR filehandle : HFILE; VAR sizetoformat : LARGE_INTEGER; VAR totalbytes : LONGLONG; VAR bytesavailable : LONGLONG; VAR sizestrbufp : PChar; VAR bufsize : UINT; VAR apiretpointer : PChar; VAR newinfoline : STRING; BEGIN filehandle := 0; FillChar(sizetoformat, SizeOf(sizetoformat), #0); FillChar(totalbytes, SizeOf(totalbytes), #0); FillChar(bytesavailable, SizeOf(bytesavailable), #0); sizestrbufp := NIL; bufsize := 0; apiretpointer := NIL; newinfoline := ''; //Format as byte newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(sizetoformat)); Memo1.Lines.Add(newinfoline); sizestrbufp := StrAlloc(64); bufsize := StrBufSize(sizestrbufp); apiretpointer := StrFormatByteSize64A(LONGLONG(sizetoformat), sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); StrDispose(sizestrbufp); //Format as KByte sizetoformat.LowPart := 12345; newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(sizetoformat)); Memo1.Lines.Add(newinfoline); sizestrbufp := StrAlloc(64); bufsize := StrBufSize(sizestrbufp); apiretpointer := StrFormatByteSize64A(LONGLONG(sizetoformat), sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); StrDispose(sizestrbufp); //Format as MByte filehandle := CreateFile('C:\Windows\System32\Shell32.dll', GENERIC_READ, FILE_SHARE_READ OR FILE_SHARE_WRITE, NIL, OPEN_EXISTING, 0, 0); sizetoformat.LowPart := GetFileSize(filehandle, @sizetoformat.HighPart); newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(sizetoformat)); Memo1.Lines.Add(newinfoline); sizestrbufp := StrAlloc(64); bufsize := StrBufSize(sizestrbufp); apiretpointer := StrFormatByteSize64A(LONGLONG(sizetoformat), sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); StrDispose(sizestrbufp); CloseHandle(filehandle); //Format as GByte FillChar(sizetoformat, SizeOf(sizetoformat), #0); GetDiskFreeSpaceEx('E:\', TLargeInteger(sizetoformat), totalbytes, @bytesavailable); newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(sizetoformat)); Memo1.Lines.Add(newinfoline); sizestrbufp := StrAlloc(64); bufsize := StrBufSize(sizestrbufp); apiretpointer := StrFormatByteSize64A(LONGLONG(sizetoformat), sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); newinfoline := ''; newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(totalbytes)); Memo1.Lines.Add(newinfoline); apiretpointer := StrFormatByteSize64A(totalbytes, sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); newinfoline := ''; newinfoline := ''; newinfoline := 'StrFormatByteSize64A called with ' + IntToStr(Int64(bytesavailable)); Memo1.Lines.Add(newinfoline); apiretpointer := StrFormatByteSize64A(bytesavailable, sizestrbufp, bufsize); newinfoline := apiretpointer; Memo1.Lines.Add(newinfoline); StrDispose(sizestrbufp); Memo1.Lines.Add(''); END;
The above example ought to produce an output similar to that below.
StrFormatByteSize64A called with 0 0 bytes StrFormatByteSize64A called with 12345 12.0 KB StrFormatByteSize64A called with 11580928 11.0 MB StrFormatByteSize64A called with 25648503808 23.8 GB StrFormatByteSize64A called with 40005271040 37.2 GB StrFormatByteSize64A called with 25648503808 23.8 GB
Requirements
Unit: Declared and imported in (SST)ShlWAPI.pas
Library: (SST)ShlWAPI.dcu/(SST)ShlWAPI.obj
Unicode: Implemented as ANSI (StrFormatByteSize64 and StrFormatByteSize64A) function(s) only.
Min. ShlWAPI.dll version according to MS SDK doc.: 5.0
Min. ShlWAPI.dll version based on SST research: 5.0
Min. OS version(s) according to Microsoft SDK doc.: NT 4.0 with IE 5, Windows 98, Windows 95 with IE 5, Windows 2000
Min. OS version(s) according to SST research: NT 4.0 with IE 5, Windows 98, Windows 95 with IE 5, Windows 2000
See Also
StrFormatByteSizeA, StrFormatByteSizeW, StrFormatKBSize.
 
Windows APIs: StrFormatByteSize, StrFormatByteSize64A, StrFormatByteSizeEx, StrFormatKBSize.


Document/Contents version 1.00
Page/URI last updated on 07.12.2023
 
Copyright © Stoelzel Software Technologie (SST) 2010 - 2017
Suggestions and comments mail to:
webmaster@stoelzelsoftwaretech.com